home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / il_c / ilSepSharpenKernel.z / ilSepSharpenKernel
Encoding:
Text File  |  2002-10-03  |  11.3 KB  |  265 lines
  1.  
  2.  
  3.  
  4. iiiillllSSSSeeeeppppSSSShhhhaaaarrrrppppeeeennnnKKKKeeeerrrrnnnneeeellll((((3333))))                 IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      iiiillllSSSSeeeeppppSSSShhhhaaaarrrrppppeeeennnnKKKKeeeerrrrnnnneeeellll - a separable kernel to do image sharpening (and
  10.      blurring)
  11.  
  12. IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM
  13.      ilSepKernel
  14.  
  15. HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
  16.      #include <il/ilCdefs.h>
  17.  
  18. CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.      This class implements a separable 2D gaussian shaped image sharpening (or
  20.      blurring  kernel).  The x and y filter weights are detemined by the
  21.      formula:
  22.  
  23.                      2           2        2
  24.                 -( dx / (2 * sigma * radius ) )
  25.               e
  26.  
  27.      where:
  28.  
  29.               sigma = radius*2 * -sharpness / 3
  30.               dx = distance from center of kernel
  31.  
  32.  
  33.      This creates a circularly symmetric, Gaussian shapped kernel.  The filter
  34.      weights are then normalized to produce an output that computes:
  35.  
  36.               (1+sharpness)*I - sharpness*G
  37.  
  38.      where I is the original image G is the orignal image with the gausing
  39.      kernel applied.
  40.  
  41.      Because of the separable nature of the kernel, the negative weights
  42.      cancel out on the corners of the kernel producing often undesirable
  43.      ringing in the filtered result; this can be avoided by using
  44.      ilSharpenKernel instead.  This is only a problem when sharpening, for
  45.      blurring the result is mathematically equivalent to the non-separable
  46.      kernel and much faster.
  47.  
  48.      Here are some example kernels with the default sharpness factor, 0.5, for
  49.      various radii:
  50.  
  51.      -.0054   1.0109   -.0054      -.0033   -.0971   1.2009   -.0971   -.0033
  52.  
  53.             rrrraaaaddddiiiiuuuussss ==== 1111                             rrrraaaaddddiiiiuuuussss ==== 2222
  54.  
  55.      The default kernel is:
  56.  
  57.                              -.0533   1.1065   -.0533
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. iiiillllSSSSeeeeppppSSSShhhhaaaarrrrppppeeeennnnKKKKeeeerrrrnnnneeeellll((((3333))))                 IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll
  71.  
  72.  
  73.  
  74.  
  75.                                    rrrraaaaddddiiiiuuuussss ==== 1111....5555
  76.      The kernel weights always sum to one and the clamping attribute is set on
  77.      this kernel so no change in the input range of values will be effected by
  78.      the application of this kernel.
  79.  
  80. CCCCLLLLAAAASSSSSSSS MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN SSSSUUUUMMMMMMMMAAAARRRRYYYY
  81.      CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr
  82.  
  83.           ilSepSharpenKernel* ilSepSharpenKernelCreate(float sharpness=.5,
  84.                                                        float radius.5)
  85.  
  86.      GGGGeeeetttt aaaannnndddd sssseeeetttt sssshhhhaaaarrrrppppeeeennnniiiinnnngggg ppppaaaarrrraaaammmmeeeetttteeeerrrrssss
  87.  
  88.           void ilSepSharpenKernelSetSharpness(ilSepSharpenKernel *obj,
  89.                                               float val)
  90.           void ilSepSharpenKernelSetRadius(ilSepSharpenKernel *obj,
  91.                                            float val)
  92.           float ilSepSharpenKernelGetSharpness(ilSepSharpenKernel *obj)
  93.           float ilSepSharpenKernelGetRadius(ilSepSharpenKernel *obj)
  94.  
  95.  
  96. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS
  97.      iiiillllSSSSeeeeppppSSSShhhhaaaarrrrppppeeeennnnKKKKeeeerrrrnnnneeeellll(((())))
  98.  
  99.           ilSepSharpenKernel* ilSepSharpenKernelCreate(float sharpness=.5,
  100.                                                        float radius.5)
  101.  
  102.  
  103.           Creates a separable kernel with the specified _s_h_a_r_p_n_e_s_s and _r_a_d_i_u_s.
  104.           The sharpness typically ranges from -1 for maximum blur, to 0 for no
  105.           effect, to positive values up to about 10 for various degrees of
  106.           sharpening.  The radius can be any non-negative value.  A radius of
  107.           zero will perform no filtering, while successively larger values
  108.           will filter lower and lower frequencies.  The actual kernel size is
  109.           determined by the formula:
  110.  
  111.               width,height = 1 + 2*(int)radius
  112.  
  113.  
  114.           Thus, a radius of 1.5 will create a 3x3 kernel.
  115.  
  116.      ggggeeeettttRRRRaaaaddddiiiiuuuussss(((())))
  117.  
  118.           float ilSepSharpenKernelGetRadius(ilSepSharpenKernel *obj)
  119.  
  120.  
  121.           This method returns the current radius of the filter as set by the
  122.           constructor or the last call to sssseeeettttRRRRaaaaddddiiiiuuuussss().
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. iiiillllSSSSeeeeppppSSSShhhhaaaarrrrppppeeeennnnKKKKeeeerrrrnnnneeeellll((((3333))))                 IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll
  137.  
  138.  
  139.  
  140.      ggggeeeettttSSSShhhhaaaarrrrppppnnnneeeessssssss(((())))
  141.  
  142.           float ilSepSharpenKernelGetSharpness(ilSepSharpenKernel *obj)
  143.  
  144.  
  145.           This method returns the current sharpness of the filter as set by
  146.           the constructor or the last call to sssseeeettttSSSShhhhaaaarrrrppppnnnneeeessssssss().
  147.  
  148.      ggggeeeettttSSSSiiiiggggmmmmaaaa(((())))
  149.  
  150.           float ilSepSharpenKernelGetSigma(ilSepSharpenKernel *obj)
  151.  
  152.  
  153.           This method returns the sigma value used in generating the kernel
  154.           (see the equation above).
  155.  
  156.      sssseeeettttRRRRaaaaddddiiiiuuuussss(((())))
  157.  
  158.           void ilSepSharpenKernelSetRadius(ilSepSharpenKernel *obj,
  159.                                            float val)
  160.  
  161.  
  162.           This method sets the radius of the kernel to _v_a_l.  The radius can be
  163.           any non-negative value. A radius of zero will perform no filtering,
  164.           while successively larger values will filter lower and lower
  165.           frequencies.  The actual kernel size is determined by the formula:
  166.  
  167.               width,height = 1 + 2*(int)radius
  168.  
  169.  
  170.           If any objects are watching this kernel (see iiiillllWWWWaaaattttcccchhhheeeeddddOOOObbbbjjjjeeeecccctttt(3))
  171.           then they will be notified that the kernel has changed when this
  172.           method is called.
  173.  
  174.      sssseeeettttSSSShhhhaaaarrrrppppnnnneeeessssssss(((())))
  175.  
  176.           void ilSepSharpenKernelSetSharpness(ilSepSharpenKernel *obj,
  177.                                               float val)
  178.  
  179.  
  180.           This method sets the sharpness of the kernel to _v_a_l.  The effect of
  181.           the sharpness value falls into three ranges: positve, between 0 and
  182.           -1, and less than -1.  As the value increases from zero the result
  183.           is a progressively more sharpended image, typically values from 0-10
  184.           are used. Values larger than about 2 produce a fairly extreme
  185.           sharpening effect.  As the value decreases from zero going to -1 the
  186.           result is a progressively more blurry image.  Values less than -1
  187.           produce a weird effect that becomes progressively sharper; this
  188.           range is not normally used.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. iiiillllSSSSeeeeppppSSSShhhhaaaarrrrppppeeeennnnKKKKeeeerrrrnnnneeeellll((((3333))))                 IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll
  203.  
  204.  
  205.  
  206.           If any objects are watching this kernel (see iiiillllWWWWaaaattttcccchhhheeeeddddOOOObbbbjjjjeeeecccctttt(3))
  207.           then they will be notified that the kernel has changed when this
  208.           method is called.
  209.  
  210.      sssseeeettttSSSSiiiiggggmmmmaaaa(((())))
  211.  
  212.           void ilSepSharpenKernelSetSigma(ilSepSharpenKernel *obj,
  213.                                           float val)
  214.  
  215.  
  216.           This method sets the sigma value used in generating the kernel (see
  217.           the equation above).  The default value is 1/3.  The useful range is
  218.           from zero to one.
  219.  
  220. IIIINNNNHHHHEEEERRRRIIIITTTTEEEEDDDD MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
  221.    IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm iiiillllSSSSeeeeppppKKKKeeeerrrrnnnneeeellll
  222.      ilSepKernelGetXdata(), ilSepKernelGetXelement(), ilSepKernelGetYdata(),
  223.      ilSepKernelGetYelement(), ilSepKernelGetZdata(),
  224.      ilSepKernelGetZelement(), ilSepKernelSetXdata(),
  225.      ilSepKernelSetXelement(), ilSepKernelSetYdata(),
  226.      ilSepKernelSetYelement(), ilSepKernelSetZdata(), ilSepKernelSetZelement()
  227.  
  228.    IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm iiiillllKKKKeeeerrrrnnnneeeellll
  229.      ilKernelCalcGain(), ilKernelCopy(), ilKernelGetData(),
  230.      ilKernelGetDataType(), ilKernelGetElement(), ilKernelGetKernelType(),
  231.      ilKernelGetOrigin(), ilKernelGetSize(), ilKernelGetXsize(),
  232.      ilKernelGetYsize(), ilKernelGetZsize(), ilKernelIsClampSet(),
  233.      ilKernelIsEquivalent(), ilKernelScale(), ilKernelSetClamp(),
  234.      ilKernelSetData(), ilKernelSetElement(), ilKernelSetOrigin()
  235.  
  236.    IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm iiiillllWWWWaaaattttcccchhhheeeeddddOOOObbbbjjjjeeeecccctttt
  237.      addWatchCallback(), doWatchCallbacks(), removeWatchCallback()
  238.  
  239. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  240.      ilWatchedObject, ilKernel, ilShapenKernel
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.